/**
 * Software License, Version 1.0
 * 
 * Copyright 2003 The Trustees of Indiana University.  All rights reserved.
 * 
 *
 *Redistribution and use in source and binary forms, with or without 
 *modification, are permitted provided that the following conditions are met:
 *
 *1) All redistributions of source code must retain the above copyright notice,
 * the list of authors in the original source code, this list of conditions and
 * the disclaimer listed in this license;
 *2) All redistributions in binary form must reproduce the above copyright 
 * notice, this list of conditions and the disclaimer listed in this license in
 * the documentation and/or other materials provided with the distribution;
 *3) Any documentation included with all redistributions must include the 
 * following acknowledgement:
 *
 *"This product includes software developed by the Community Grids Lab. For 
 * further information contact the Community Grids Lab at 
 * http://communitygrids.iu.edu/."
 *
 * Alternatively, this acknowledgement may appear in the software itself, and 
 * wherever such third-party acknowledgments normally appear.
 * 
 *4) The name Indiana University or Community Grids Lab or NaradaBrokering, 
 * shall not be used to endorse or promote products derived from this software 
 * without prior written permission from Indiana University.  For written 
 * permission, please contact the Advanced Research and Technology Institute 
 * ("ARTI") at 351 West 10th Street, Indianapolis, Indiana 46202.
 *5) Products derived from this software may not be called NaradaBrokering, 
 * nor may Indiana University or Community Grids Lab or NaradaBrokering appear
 * in their name, without prior written permission of ARTI.
 * 
 *
 * Indiana University provides no reassurances that the source code provided 
 * does not infringe the patent or any other intellectual property rights of 
 * any other entity.  Indiana University disclaims any liability to any 
 * recipient for claims brought by any other entity based on infringement of 
 * intellectual property rights or otherwise.  
 *
 *LICENSEE UNDERSTANDS THAT SOFTWARE IS PROVIDED "AS IS" FOR WHICH NO 
 *WARRANTIES AS TO CAPABILITIES OR ACCURACY ARE MADE. INDIANA UNIVERSITY GIVES
 *NO WARRANTIES AND MAKES NO REPRESENTATION THAT SOFTWARE IS FREE OF 
 *INFRINGEMENT OF THIRD PARTY PATENT, COPYRIGHT, OR OTHER PROPRIETARY RIGHTS. 
 *INDIANA UNIVERSITY MAKES NO WARRANTIES THAT SOFTWARE IS FREE FROM "BUGS", 
 *"VIRUSES", "TROJAN HORSES", "TRAP DOORS", "WORMS", OR OTHER HARMFUL CODE.  
 *LICENSEE ASSUMES THE ENTIRE RISK AS TO THE PERFORMANCE OF SOFTWARE AND/OR 
 *ASSOCIATED MATERIALS, AND TO THE PERFORMANCE AND VALIDITY OF INFORMATION 
 *GENERATED USING SOFTWARE.
 */
package cgl.narada.transport;


/** A Link is an abstraction that hides details pertaining to communications. 
    Implementations of the link interface can incorporate their own handshaking
    protocols for setting up of the communication link. Links also contain 
    methods which allow for checking the status of the underlying communication
    mechanism at specified intervals. Loss of communications should be reported
    to the transport handler interface.
    <p>
    Each implementation of the Link can expose and measure a set of performance
    factors. Measurement of performance factors over links requires cooperation
    from the other end-point of the communication link; this particular detail 
    should be handled within the link implementation itself. How the link 
    computes round trip delays, jitter factors, bandwidth, loss rates etc. 
    should be within the domain of the link implementer. Links also have 
    methods which enable/disable the measurement of these performance factors.
    Links also allow the specification of constraints (usually on the set of 
    performance factors that it measures) and the link type that the 
    communication must migrate to when those conditions are satisfied. Links 
    expose the performance related information in the LinkPerformanceData 
    construct.
    
    @author Shrideep Pallickara
    $Date$
    $Revision$
*/


public interface Link {
  
  /** The method used to send data over a communication link */
  public void sendData(byte[] data) throws TransportException;
  
  /** The method used to send data over a communication link, this method 
      also includes information regarding the type (audio/video/xml-attachments
      etc.) of the data encapsulated within the data stream. Using this
      information links can optimally flush/send data across the link
  */ 
  public void sendData(byte[] data, String dataType) throws TransportException;

  /** Sets the Id of the communication link */
  public void setLinkId(String stringId);
  
  
  /** Retrieves the String based id of the link */
  public String getLinkId();

  /** The Naradabrokering Id of the node this link interacts with */
  public void setNaradaBrokeringId(Object BrokeringId);
  
  /** Returns the NaradaBrokeringId associated with this link */
  public Object getNaradaBrokeringId();
  
  /** Returns the type of the communication link */
  public String getLinkType();
  
  /** Sets the conditions under which communication protocols need to be
      switched and the transport link that it should be switched to under
      the condition. Multiple constraints can be set signifying migration to
      different protocols.  */
  public void setLinkMigrationConstraint(String constraint, 
					    String linkType);
  
  /** Check the status of the communication link at intervals specified in
      the argument of this method */
  public void setLinkStatusInterval(long interval);
  
  /** Used to enable or disable performance gathering on a communication
      link */
  public void setPerformanceGathering(boolean gather);
  
  /** Used to test weather performing gathering is enabled for a given
      communication link */
  public boolean performanceGatheringEnabled();
  
  /** Returns the list of performance factors that are measured on this 
      communication link */
  public String[] getPerformanceFactorsMeasured();
  
  /** Returns the complete set of performance factors measured and their
      corresponding values*/
  public LinkPerformanceData[] getAllPerformanceData();
  
  /** Returns the value of a performance factor as a string */
  public String getPerformanceData(String factorName);


  /** Set the amount of time after which resources associated with this 
      link need to be garbage collected. A value of '0' indicates that 
      this link needs to be active at all times. */
  public void setKeepAliveTime(long keepAliveTime);
  
  /** Garbage collect resources associated with this link. Sockets need to
      be closed and any resources associated with communication, needs to be
      garbage collected */
  public void closeLink();

  /** Indicates weather communication is encrypted on this link */
  public boolean isSecure();
  
  /** Information pertaining to the security strategy adopted for this
      communication link */
  public String getSecurityInformation();

}
